OneNote 2013

 Copy code hover
[image]

OneNote 2013
Send feedback

OneNote product logo

Use OneNote 2013 to create and automatically store all your notes.

Explore OneNote 2013 developer resources

Get started

Get started

OneNote for developers

References

Reference

OneNote 2013 developer reference

Find training and other resources about Office

Email us to suggest content Subscribe to the Office developer RSS Read Office developer blogs Read Office developer forums Visit MSDN Office and SharePoint on Facebook Follow @MSDN_Office on Twitter

Download

Office updates

Office 365

Office code samples

Office scripts and sample files

Office downloads

Office 365 downloads

How To

Train Office 2010 end users

Office developer videos

Office IT pro training

Office IT pro videos

Sites

Office 365 IT pros

Office 2013 Resource Kit

SharePoint developers

SharePoint IT pros

Office.com

Microsoft.com: Office 365

Additional resources

  • Access 2013

  • Excel 2013

  • InfoPath 2013

  • Office 2013

  • Outlook 2013

  • PowerPoint 2013

  • Project 2013

  • Publisher 2013

  • SharePoint 2013

  • Visio 2013

  • Word 2013

© 2013 Microsoft Corporation. All rights reserved.


Welcome to the OneNote 2013 developer reference

 Copy code hover
[image]

Welcome to the OneNote 2013 developer reference
Send feedback

This reference contains conceptual overviews and programmatic references to guide you in developing solutions based on OneNote 2013. It includes all the additions and changes to the OneNote 2013 application programming interface (API), and provides code samples in C# to show how to perform some tasks in OneNote. The OneNote 2013 API enables users to programmatically access and edit OneNote content. Users can also make changes to the view of OneNote windows.

Initial publication: October 2012 | Updated: November 2012

This documentation contains the following information:

  • Window interfaces: Describes the Window and Windows interfaces, which enable users to enumerate through the set of OneNote windows and modify certain window properties.

  • Quick Filing dialog box interfaces: Describes the interfaces that you can use to programmatically customize the Quick Filing dialog box in OneNote 2013.

  • Application interface: Describes methods, properties, and events that help retrieve, manipulate, and update OneNote 2013 information and content.

  • Enumerations: Describes the enumerations in the OneNote 2013 object model.

  • Error codes: Lists the error codes in the OneNote 2013 object model.

Additional resources

  • OneNote for developers

  • Accessibility in Microsoft Products

  • Document Conventions

  • OneNote 2013 Developer Reference Copyright Information

  • Microsoft Online Privacy Notice


Window interfaces (OneNote 2013)

 Copy code hover
[image]

Window interfaces (OneNote 2013)
See also Send feedback

The Window and Windows interfaces are OneNote 2013 API objects that enables users to work with OneNote windows. These objects allow users to enumerate through the set of OneNote windows and modify certain window properties.

OneNote Window Views

The following list shows the four view modes that you can use for OneNote windows:

  • Normal view—Displays the default OneNote window in which the Notebook and Page navigation panes are visible.

  • Full Page view—Displays a minimal user-interface (UI) view in which the Notebook and Page panes are not displayed.

  • Quick note—Displays a small window that allows users to take short notes. You would usually access quick notes through the OneNote icon in the Windows notification area, but you can also access them through the View tab in OneNote.

  • Dock to Desktop—Displays a OneNote window that you can dock to any side of the desktop (similar to the taskbar). This view reduces the size of the desktop to fit the window. You can dock only one window at any time, and the window is always visible without blocking the desktop.

Figure 1 shows what the Full Page view, Dock to Desktop view, and quick notes look like on your desktop.

Figure 1. OneNote views

OneNote window views

Interfaces

This section lists the interfaces and members that you can use to modify OneNote windows programmatically.

Windows Interface

The Windows interface allows the user to access the set of opened OneNote windows. It is a property of the OneNote Application class, accessed through Application.Windows. This returns the enumerated set of OneNote windows.

Properties
Name | Type | Description
Count | ulong | Gets the number of Window objects in the Windows set.
CurrentWindow | Window | Gets the Window object of the active OneNote window.
Items | Window | Returns the Window object that corresponds to the index value passed. This property cannot be accessed directly. To return a Window object, use Windows [(uint) index].

Window Interface

The Window interface allows the user to access certain properties of each window. Each OneNote window can be accessed by enumerating through the Windows property of the Application class.

Properties
Name | Type | Description
Active | bool | Gets or sets a value that indicates whether the window is the active OneNote window.
Application | Application | Gets the OneNote Application object that is associated with the window.
CurrentPageId | string | Gets the object ID of the active OneNote page of the window.
CurrentSectionId | string | Gets the object ID of the active OneNote section of the window.
CurrentSectionGroupId | string | Gets the object ID of the active OneNote section group of the window.
CurrentNotebookId | string | Gets the object ID of the active OneNote notebook of the window.
DockedLocation | DockedLocation | Gets or sets the docked location of the OneNote window.
FullPageView | bool | Gets or sets a value that indicates whether the window is in Full Page view (minimal UI view).
SideNote | bool | Gets or sets a value that indicates whether the window is a quick note window.
WindowHandle | ulong | Gets the handle ID of the OneNote window.

Methods

You can use the following methods of the Window interface to navigate to specified objects in the OneNote window or to specified URLs.

NavigateTo

Description

Navigates to the specified object in the OneNote window. For example, you can navigate to sections, pages, and outline elements within pages.

Syntax

HRESULT NavigateTo(
[in]BSTR bstrHierarchyObjectID,
[in]BSTR bstrObjectID);

Parameters

  • bstrHierarchyObjectID—The hierarchy OneNote ID of the object you want to navigate to. The object ID can reference a OneNote notebook, section, section group, or page.

  • bstrObjectID—The OneNote ID of the specific object to navigate to within a OneNote page. If the user does not want to navigate to a specific object on a page, this parameter is set to null.
NavigateToUrl
Description | If passed a OneNote link (onenote://), opens the OneNote window to the corresponding location in OneNote. However, if the link is an external link, such as http:// or file://, a security dialog box will appear. Upon dismissal, OneNote attempts to open up the link and an HResult.hrObjectDoesNotExist error is returned.
Syntax | HRESULT NavigateToUrl ( [in]BSTR bstrUrl);
Parameters | bstrUrl—The URL to navigate to.
SetDockedLocation

Description

Docks the window to the location specified by dockLocation and the monitor at ptMonitor.

Syntax

HRESULT SetDockedLocation(
[in] DockLocation dockLocation,
[in] POINT ptMonitor);

Parameters

  • dockLocation - Indicates the docked location of a OneNote 2013 window.

  • ptMonitor - (Optional) Indicates in x,y co-ordinates which monitor the window should be docked to.

Example

The following code iterates through the OneNote windows to find a docked window. If no docked window exists, the example docks the active window. If no active window exists, the code creates a new docked window.

C# Copy code Copy code
using System;
using System.Diagnostics;
using Microsoft.Office.Interop.OneNote;

namespace SampleWND
{
    class DockOneNoteWindow
    {
        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app = new Microsoft.Office.Interop.OneNote.Application();

            // Search through all OneNote windows for a docked window and activate it.
            bool foundDockedWND = false;
            for (int i = 0; i < app.Windows.Count; i++)
            {
                if (app.Windows[(uint) i].DockedLocation != DockLocation.dlNone)
                {
                    foundDockedWND = true;
                    app.Windows[(uint) i].Active = true;
                }
            }

            // If no docked window exists, dock the active window.
            if (!foundDockedWND && (app.Windows.Count > 0))
                app.Windows.CurrentWindow.DockedLocation = DockLocation.dlDefault;

            // If no active window exists, create a new docked window.
            if (app.Windows.Count < 1)
            {
                Process oneProc = new Process();
                oneProc.StartInfo.FileName = "onenote.exe";
                oneProc.StartInfo.Arguments = "/docked";
                oneProc.Start();
            }
        }
    }
}

See also

Concepts

Welcome to the OneNote 2013 developer reference


Quick Filing dialog box interfaces (OneNote 2013)

 Copy code hover
[image]

Quick Filing dialog box interfaces (OneNote 2013)
See also Send feedback

This topic describes the interfaces that you can use to programmatically customize the Quick Filing dialog box in OneNote 2013.

Quick Filing Dialog Box

The Quick Filing dialog box in OneNote 2013 is a customizable dialog box that allows users to select a location within the OneNote hierarchy structure. Selectable locations include notebooks, section groups, sections, pages, and subpages. The dialog box is used both within the OneNote application and by external applications through the OneNote 2013 API. Figure 1 shows the Quick Filing dialog box in its default state.

Figure 1. Quick Filing dialog box without customizations

Quick Filing dialog box without customizations

Within the dialog box, users can navigate the All Notebooks hierarchy to look for specific locations or search the OneNote tree structure by typing into the text box. Aspects of the dialog box that can be customized include the title, description, recent results list, check box text and state, tree depth, buttons, and selectable location types.

Interfaces

You can access the Quick Filing dialog box functionality through two OneNote 2013 interfaces. The IQuickFilingDialog interface allows users to instantiate, set up, and run the dialog box. The IQuickFilingDialogCallback interface is called after the dialog box is closed. The dialog box is run in the OneNote process, so a mechanism is needed to keep the dialog box's thread running and then to capture the user's selection and the state of the dialog box when it is closed.

IQuickFilingDialog Interface

This interface allows the user to customize and run the dialog box. The user can instantiate a dialog box through the Application class by using the Application.QuickFilingDialog method. The method returns an instance of the dialog box. Once the properties of the dialog box are set, the IQuickFilingDialog.Run method is used to run the dialog box. This method runs the dialog box on a new thread.

Properties

Name

Type

Description

Title

string

Gets or sets the title text that appears in the title bar of the dialog box window.

Description

string

Gets or sets the text description to instruct the user about what to select. This value can be multiple-line text.

CheckboxText

string

Gets or sets the text that follows the check box. If this value is set to a non-empty string, a check box appears in the dialog box. If the value is an empty string, no check box appears.

CheckboxState

bool

Gets or sets the state of the check box. If value is set to false, the check box is cleared when the dialog box is started. If the value is set to true, the check box is selected when the dialog box is started as long as CheckboxText is a non-empty string.

WindowHandle

ulong

Gets the handle ID of the Quick Filing dialog box window.

TreeDepth

HierarchyElement

Gets or sets how deep the OneNote tree should be displayed in the All Notebooks section. By default, the tree is displayed up to the sections. This property does not affect what type of elements can be selected.

If TreeDepth is set to an element lower in the OneNote hierarchy than can be selected by any of the buttons, the displayed tree depth will be the lowest possible selectable element. That is, if tree depth is set to display down to pages, but the lowest selectable element is a section, the tree is displayed down to sections.

ParentWindowHandle

ulong

Gets or sets the handle ID of the parent window of the dialog box. If this property is set, the Quick Filing dialog box will be modal to the assigned parent window when the dialog box opens. That is, a user will not be able to access the parent window until the Quick Filing dialog box is closed.

Position

tagPOINT

Gets or sets the position of the window in relation to the screen. By default, the dialog box appears in the middle of the parent window or the desktop.

SelectedItem

string

Gets the object ID of the OneNote location selected by the user when the dialog box is closed. If the user clicks the Cancel button, the object is set to null.

PressedButton

ulong

Gets which button was clicked when the dialog box was closed. If the Cancel button was clicked, this property returns a value of -1. All other buttons are assigned integer values from 0, incremented by 1 for each button added to the dialog box. The integer value of the default OK button is 0.

Methods

SetRecentResults

Description

Sets what recent result list will be displayed in the Quick Filing dialog box, and indicates whether to include some special filing locations in the list. Users can select a recent result list from the RecentResultType enumeration. Users can also choose to add the following options to the list: Current Section, Current Page, or Unfiled Notes. If RecentResultType.rrtNone is selected, no recent result list is shown.

Syntax

HRESULT SetRecentResults (
[in]RecentResultType recentResults,
[in]VARIANT_BOOL fShowCurrentSection,
[in]VARIANT_BOOL fShowCurrentPage,
[in]VARIANT_BOOL fShowUnfiledNotes);

Parameters

  • recentResults—An object of type RecentResultType that indicates which recent result list, if any, should appear. If rrtNone is selected, no recent result list appears in the dialog box.

  • fShowCurrentSection—A Boolean value that indicates whether the current section should be included in the recent result list.

  • fShowCurrentPage—A Boolean value that indicates whether the current page should be included in the recent result list.

  • fShowUnfiledNotes—A Boolean value that indicates whether the Unfiled Notes section should be included in the recent result list.
Note Note

If a special filing location cannot be selected by using any of the buttons in the dialog box, it is not shown in the list. If no selectable item in the recent results list is found, no recent result list is displayed.

The following example uses the SetRecentResults method to display the current section, current page, and the Unfiled Notes section in the recent result list.

C# Copy code Copy code
        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app =
                new Microsoft.Office.Interop.OneNote.Application();
            ...

            // RECENT RESULTS
            qfDialog.SetRecentResults(RecentResultType.rrtFiling,
                /*Current Section*/ true,
                /*Current Page*/ true,
                /*Unfiled Notes*/ true);
            ...

        }
AddButton

Description

Allows users to add and customize buttons in the dialog box. Users can specify the text on the buttons and what elements of the OneNote hierarchy can be selected by each button.

Syntax

HRESULT AddButton (
[in]BSTR bstrText,
[in]HierarchyElement allowedElements,
[in]HierarchyElement allowedReadOnlyElements,
[in]VARIANT_BOOL fDefault);

Parameters

  • bstrText—A string that specifies the text to appear on the button. To customize the default OK button, pass in a null value as bstrText.

  • allowedElements—A HierarchyElement that indicates what non-read-only OneNote hierarchy elements a user is allowed to select by using the button. For selecting multiple items, the user should pass in the OR operator for all the uint equivalent values of the HierarchyElement types allowed as a HierarchyElement.

  • allowedReadOnlyElements—A HierarchyElement that indicates what OneNote read-only hierarchy elements a user is allowed to select by using the button. For selecting multiple items, the user should pass in the OR operator for all the uint equivalents values of the HierarchyElement types allowed as a HierarchyElement.

  • fDefault—A Boolean value that specifies whether this button should be the default button. If multiple buttons are set as default, the last specified button becomes the default button.

The following example adds three buttons to the Quick Filing dialog box. The first one, All, can be selected by all elements in the OneNote hierarchy tree. The others, Notebooks and Pages, can be selected only if their corresponding elements, Notebooks and Pages, are selected.

C# Copy code Copy code
        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app =
                new Microsoft.Office.Interop.OneNote.Application();
            ...

            // BUTTONS
            HierarchyElement heAll = (HierarchyElement)
                ((uint)HierarchyElement.heNotebooks |
                (uint)HierarchyElement.heSectionGroups |
                (uint)HierarchyElement.heSections |
                (uint)HierarchyElement.hePages);

            qfDialog.AddButton("All", heAll, heAll, true);
            qfDialog.AddButton("Notebooks", HierarchyElement.heNotebooks,
                HierarchyElement.heNotebooks, false);
            qfDialog.AddButton("Pages", HierarchyElement.hePages,
                HierarchyElement.hePages, false);
            ...
        }
Run
Description | Displays the Quick Filing dialog box from a new thread. It takes a reference to the IQuickFilingDialogCallback interface, whose OnDialogClosed method will be called once the dialog box closes.
Syntax | HRESULT Run ( [in]IQuickFilingDialogCallback piCallback);
Parameters | piCallback—A reference to the IQuickFilingDialogCallback interface that will be instantiated once the dialog box closes.

The following example uses the Run method to display the Quick Filing dialog box from a new thread.

C# Copy code Copy code
    class OpenQuickFilingDialog
    {
            ...

        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app =
                new Microsoft.Office.Interop.OneNote.Application();
            ...

            // Display Quick Filing UI
            qfDialog.Run(new Callback());

            ...
        }

    }
TreeCollapsedState
Description | Indicates whether the hierarchy tree should be expanded or collapsed.
Syntax | HRESULT TreeCollapsedState( [in] TreeCollapsedStateType tcs);
Parameters | tcs - Specifies whether the tree is expanded or collapsed.
NotebookFilterOut
Description | Filters the list of notebooks shown by type.
Syntax | HRESULT NotebookFilterOut( [in] NotebookFilterOutType nfo);
Parameters | nfo - Specifies the set of notebooks that are to be filtered out of the list
ShowCreateNewNotebook
Description | Displays the create new notebook option in the dialog.
Syntax | HRESULT ShowCreateNewNotebook ();
Parameters | None
AddInitialEditor
Description | Adds a user as an initial editor to a notebook in the Quick Filing dialog box.
Syntax | HRESULT AddInitialEditor (BSTR initialEditor);
Parameters | initialEditor - The email address of the user you wish to add as an editor to the notebook. When the notebook is created via the Quick Filing dialog box, it is automatically shared with all Initial Editors.
ClearInitialEditors
Description | Removes all initial editors from the Quick Filing dialog box.
Syntax | HRESULT ClearInitialEditors ();
Parameters | None
ShowSharingHyperlink
Description | Displays the Sharing Help Topic Hyperlink in the Quick Filing dialog box.
Syntax | HRESULT ShowSharingHyperlink();
Parameters | None

IQuickFilingDialogCallback Interface

This interface allows the user to access the dialog box properties after the dialog box closes. Once the dialog box closes, OneNote 2013 calls the IQuickFilingDialogCallback.OnDialogClose method in this interface.

A class that inherits this interface has to be defined.

Methods

The following section describes the methods associated with the interfaces detailed previously.

OnDialogClosed
Description | Enables users to add functionality to capture and use the user selection from the dialog box. This method is called after the Quick Filing dialog box is closed. This method is a function that IQuickFilingDialogCallback interfaces have to define.
Syntax | HRESULT OnDialogClosed ( [in]IQuickFilingDialog dialog);
Parameters | dialog—The IQuickFilingDialog object that called the OnDialogClose method.

The following example is a sample IQuickFilingDialogCallback interface. The OnDialogClose method prints the user's selection from the Quick Filing dialog box to the console.

C# Copy code Copy code
    class Callback : IQuickFilingDialogCallback
    {
        public Callback(){}

        public void OnDialogClosed(IQuickFilingDialog qfDialog)
        {
            Console.WriteLine(qfDialog.SelectedItem);
            Console.WriteLine(qfDialog.PressedButton);
            Console.WriteLine(qfDialog.CheckboxState);
        }
    }

Example

The following code example opens a Quick Filing dialog box that has a customized title, description, recent result list, tree depth, check box, and buttons. The user's selected item, pressed button, and check-box state will be displayed in a console window when the dialog box is closed. To see the page button enabled, the user will have to search for a page and select it, because the tree depth is set down to sections. The dialog box is not a child of any window.

C# Copy code Copy code
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading;
using Microsoft.Office.Interop.OneNote;

namespace SampleQFD
{
    class OpenQuickFilingDialog
    {
        private static EventWaitHandle wh = new AutoResetEvent(false);
        private static IQuickFilingDialog qfDialog;

        private static String strTitle = "Sample Title";
        private static String strDescription = "Sample Description";
        private static String strCheckboxText = "Sample Checkbox";

        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app =
                new Microsoft.Office.Interop.OneNote.Application();

            // Instantiate Quick Filing UI
            qfDialog = app.QuickFiling();

            #region//SET API PARAMETERS
            // TITLE
            qfDialog.Title = strTitle;

            // DESCRIPTION
            qfDialog.Description = strDescription;

            // RECENT RESULTS
            qfDialog.SetRecentResults(RecentResultType.rrtFiling,
                /*Current Section*/ true,
                /*Current Page*/ true,
                /*Unfiled Notes*/ true);

            // TREE DEPTH
            qfDialog.TreeDepth = HierarchyElement.heSections;

            // CHECKBOX
            qfDialog.CheckboxText = strCheckboxText;
            qfDialog.CheckboxState = false;

            // BUTTONS
            HierarchyElement heAll = (HierarchyElement)
                ((uint)HierarchyElement.heNotebooks |
                (uint)HierarchyElement.heSectionGroups |
                (uint)HierarchyElement.heSections |
                (uint)HierarchyElement.hePages);

            qfDialog.AddButton("All", heAll, heAll, true);
            qfDialog.AddButton("Notebooks", HierarchyElement.heNotebooks,
                HierarchyElement.heNotebooks, false);
            qfDialog.AddButton("Pages", HierarchyElement.hePages,
                HierarchyElement.hePages, false);

            // PARENTWINDOW
            #endregion

            // Display Quick Filing UI
            qfDialog.Run(new Callback());

            // Clean up and Wait so console window does not close
            qfDialog = null;
            wh.WaitOne();
        }

    }

    class Callback : IQuickFilingDialogCallback
    {
        public Callback(){}

        public void OnDialogClosed(IQuickFilingDialog qfDialog)
        {
            Console.WriteLine(qfDialog.SelectedItem);
            Console.WriteLine(qfDialog.PressedButton);
            Console.WriteLine(qfDialog.CheckboxState);
        }
    }
}

See also

Welcome to the OneNote 2013 developer reference


Application interface (OneNote 2013)

 Copy code hover
[image]

Application interface (OneNote 2013)
See also Send feedback

The Application interface includes methods help retrieve, manipulate, and update OneNote information and content. The methods are in four general categories:

  • Notebook structure—Methods for working with notebook structure, including those for discovering, opening, modifying, closing, and deleting notebooks, section groups, and sections.

  • Page content—Methods for working with pages and page content, including those for discovering, modifying, saving, and deleting page content. Page content includes binary objects, such as ink and images, and text objects, such as outlines.

  • Navigation—Methods for finding, linking to, and navigating to pages and objects.

  • Functional—All other methods that perform certain actions or set parameters in OneNote.

In addition, the Application interface includes a number of properties and events.

Notebook Structure Methods

The methods described in this section enable you to discover, open, modify, close, and delete OneNote notebooks, section groups, and sections.

GetHierarchy Method

Description

Gets the notebook node hierarchy structure, starting from the node you specify (all notebooks or a single notebook, section group, or section), and extending downward to all descendants at the level you specify.

Syntax

HRESULT GetHierarchy(
[in]BSTR bstrStartNodeID,
[in]HierarchyScope hsScope,
[out]BSTR * pbstrHierarchyXmlOut,
[in,defaultvalue(xs2013)]XMLSchema xsSchema);

Parameters

  • bstrStartNodeID—The node (notebook, section group, or section) whose descendants you want. If you pass a null string (""), the method gets all nodes below the root node (that is, all notebooks, section groups, and sections). If you specify a notebook, section group, or section node, the method gets only descendants of that node.

  • hsScope—The lowest descendant node level you want. For example, if you specify pages, the method gets all nodes as far down as the page level. If you specify sections, the method gets only section nodes below the notebook. For more information, see the HierarchyScope enumeration in the Enumerations topic.

  • pbstrHierarchyXmlOut—(Output parameter) A pointer to the string in which you want OneNote to write the XML output.

  • xsSchema—(Optional) The version of the OneNote XML schema, of type XMLSchema, that you want to be output. You can specify whether you want XML Schema version 2013, 2010, 2007, or the current version.

    Note Note

    We recommend specifying a version of OneNote (such as xs2013) instead of using xsCurrent or leaving it blank, because this will allow your add-in to work with future versions of OneNote.

The GetHierarchy method returns a string in OneNote 2013 XML format by default or you can set the preferred XML schema version by using the optional xsSchema parameter.

Depending on the parameters you pass, the GetHierarchy method can return various lists (for example all notebooks, all sections in all notebooks, all pages within a given section, or all pages within a given notebook). For each node, the XML string returned provides properties (for example, the section or page title, ID, and last-modified time).

Not all combinations of start node and scope are valid. For example, if you specify a section start node and a notebook scope, GetHierarchy returns a null result because a notebook is higher in the node hierarchy than a section.

The following C# example shows how to use the GetHierarchy method to get the entire OneNote hierarchy, including all notebooks, down to the page level. It copies the output string to the Clipboard, from which you can paste the string into a text editor for review.

C# Copy code Copy code
static void GetEntireHierarchy()
    {
        String strXML;
        OneNote.Application onApplication = new OneNote.Application();
        onApplication.GetHierarchy(null,
            OneNote.HierarchyScope.hsPages, out strXML);
        Clipboard.SetText(strXML);
        MessageBox.Show("The XML has been copied to the clipboard");
    }

UpdateHierarchy Method

Description

Modifies or updates the hierarchy of notebooks. For example, you can add sections or section groups to a notebook, add a new notebook, move sections within a notebook, change the name of a section, add pages to a section, or change the order of pages within sections.

Syntax

HRESULT UpdateHierarchy(
[in]BSTR bstrChangesXmlIn,
[in,defaultvalue(xsCurrent)] XMLSchema xsSchema);

Parameters

  • bstrChangesXmlIn—A string that contains OneNote XML code that specifies the hierarchy changes to make. For example, if you want to insert a new section, you can add a Section element in the XML string to indicate where you want the new section to be added. Alternatively, if you want to change the name of an existing section, you can keep the same section ID and change its name attribute in the XML code.

  • xsSchema—(Optional) The OneNote schema version of the string bstrChangesXmln. This optional value is used to specify the version of the OneNote XML schema that the bstrChangesXmlIn string is in. If this value is not specified, OneNote will assume that the XML is in schema version xsCurrent.

    Note Note

    We recommend specifying a version of OneNote (such as xs2013) instead of using xsCurrent or leaving it blank, because this will allow your add-in to work with future versions of OneNote.

If you pass only a partial OneNote XML string for the bstrChangesXmlIn parameter, OneNote attempts to infer the changes you want. For example, if you include a Notebook element that contains only one section, OneNote adds the section after any existing sections. However, if the operation you specify is ambiguous, the result can be hard to determine. For example, if an existing notebook contains four sections, and the XML string you pass includes the notebook and only the fourth and first sections (in that order), OneNote might place the second and third sections before the fourth section or after the first section.

You cannot use the UpdateHierarchy method to delete part of a notebook. That is, passing an XML string that includes only part of an existing hierarchy does not delete sections that are not included in the string. To delete part of a hierarchy, use the DeleteHierarchy method.

The following C# code shows one way to use the UpdateHierarchy method to change the OneNote hierarchy, by changing the name of an existing section. It reads XML code from a sample file named ChangeSectionName.xml at the root of drive C, loads it into an XML document, and then passes the XML structure of that document to the method.

C# Copy code Copy code
static void UpdateExistingHierarchy()
    {
        OneNote.Application onApplication = new OneNote.Application();

        // Get the XML from the file.
        XmlTextReader reader = new XmlTextReader("C:\\ChangeSectionName.xml");
        reader.WhitespaceHandling = WhitespaceHandling.None;
        XmlDocument xmlDocIn = new XmlDocument();
        xmlDocIn.Load(reader);

        // Update the hierarchy.
        onApplication.UpdateHierarchy(xmlDocIn.OuterXml,
        OneNote.XMLSchema.xs2007);
    }

The following XML code is an excerpt of the ChangeSectionName.xml file that the previous C# code passes to the method. When the XML is passed to the UpdateHierarchy method, it changes the name of one of the sections in the existing hierarchy (by changing the value of the name attribute to "My Renamed Section"). It then removes all the sections except the one whose name was changed. In addition, the code removes unnecessary attributes from the target Section element, including the lastModifiedTime, isCurrentlyViewed, and color attributes, leaving only the name, ID, and path attributes intact.

XML Copy code Copy code
<?xml version="1.0" ?>
    <one:Notebooks xmlns:one="http://schemas.microsoft.com/office/onenote/12/2004/onenote">
        <one:Notebook name="My Notebook" nickname="My Notebook" ID="{0B8E7305-AC2C-4BCB-8651-1CDA55AAE14C}{1}{B0}">
            <one:Section name="My Renamed Section" ID="{5F4E2908-44BA-4C02-91FE-49FC665E9A33}{1}{B0}" path="C:\My Section.one" />
        </one:Notebook>
    </one:Notebooks>

The preceding XML code was obtained by using the code shown in the example for the GetHierarchy method, which is modified, as follows, to limit the scope to sections.

C# Copy code Copy code
static void GetAllSections()
    {
        String strXML;
        OneNote.Application onApplication = new OneNote.Application();
        onApplication.GetHierarchy(System.String.Empty,
            OneNote.HierarchyScope.hsSections, out strXML);
        Clipboard.SetText(strXML.ToString());
        MessageBox.Show("The XML has been copied to the Clipboard");
    }

The following C# example shows a complete console application that searches for a section named "Sample_Section", prompts the user to input a new name for the section, and then uses the UpdateHierarchy method to change the section name to the name that the user typed. Before running the code, change "Sample_Section" to the name of a section that exists in your OneNote hierarchy.

C# Copy code Copy code
    static void Main(string[] args)
    {

        // OneNote 2013 Schema namespace.
        string strNamespace = "http://schemas.microsoft.com/office/onenote/2013/onenote";
        string outputXML;

        Application onApplication = new Application();
        onApplication.GetHierarchy(null, HierarchyScope.hsSections, out outputXML);

        // Load a new XmlDocument.
        XmlDocument xmlDoc = new XmlDocument();
        xmlDoc.LoadXml(outputXML);
        XmlNamespaceManager nsmgr = new XmlNamespaceManager(xmlDoc.NameTable);
            nsmgr.AddNamespace("one", strNamespace);

        // Search for the section named "Sample_Section".
        XmlNode xmlNode = xmlDoc.SelectSingleNode("//one:Section[@name='Sample_Section']", nsmgr);

        // Prompt for a new section title.
        System.Console.Write("Please enter a new title for the section: ");
        string input = System.Console.ReadLine();
        xmlNode.Attributes["name"].Value = input;

        // Update the section with the new title.
        onApp.UpdateHierarchy(xmlNode.OuterXml);
        System.Console.Write("Done!\n");

    }

OpenHierarchy Method

Description

Opens a section group or section that you specify.

Syntax

HRESULT OpenHierarchy(
[in]BSTR bstrPath,
[in]BSTR bstrRelativeToObjectID,
[out]BSTR * pbstrObjectID,
[in,defaultvalue(cftNone)]CreateFileType cftIfNotExist);

Parameters

  • bstrPath—The path that you want to open. For a notebook, or for a section group in a notebook, bstrPath can be a folder path or the path to an .one section file. If you specify the path to an .one section file, you must include the .one extension on the file-path string.

  • bstrRelativeToObjectID—The OneNote ID of the parent object (notebook or section group) under which you want the new object to open. If the bstrPath parameter is an absolute path, you can pass an empty string ("") for bstrRelativeToObjectID. Alternatively, you can pass the object ID of the notebook or section group that should contain the object (section or section group) that you want to create, and then specify the file name (for example, section1.one) of the object that you want to create under that parent object.

  • pbstrObjectID—(Output parameter) The object ID that OneNote returns for the notebook, section group, or section that the OpenHierarchy method opens. This parameter is a pointer to the string into which you want the method to write the ID.

  • cftlfNotExist—(Optional) An enumerated value from the CreateFileType enumeration. If you pass a value for cftIfNotExist, the OpenHierarchy method creates the section group or section file at the specified path only if the file does not already exist.

If you specify a section group that is not in an open notebook, the OpenHierarchy method opens the section group as a notebook. If you specify a section that is not in an open notebook, the OpenHierarchy method opens the section in the Recent Opened Sections section group. If you specify a section group or section that is already in an open notebook, nothing happens because the section group or section is already open, as well. In any case, OpenHierarchy returns the object ID for the section group, notebook, or section that you specify, so that you can use it in other operations.

You can also use the OpenHierarchy method to create new sections, instead of doing so by importing XML.

The following code shows how to use the OpenHierarchy method to open the Meetings section in the Work notebook and get the ID for the section. If the section does not already exist, OneNote creates it in the location that you specify.

C# Copy code Copy code
static void OpenSection()
    {
        String strID;
        OneNote.Application onApplication = new OneNote.Application();
        onApplication.OpenHierarchy("C:\\Documents and Settings\\user\\My Documents\\OneNote Notebooks\\Work\\Meetings.one",
        System.String.Empty, out strID, OneNote.CreateFileType.cftSection);
    }

DeleteHierarchy Method

Description

Deletes any hierarchy object (a section group, section, or page) from the OneNote notebook hierarchy.

Syntax

HRESULT DeleteHierarchy(
[in]BSTR bstrObjectID,
[in,defaultvalue(0)]DATE dateExpectedLastModified,
[in,defaultvalue(false)]VARIANT_BOOL deletePermanently);

Parameters

  • bstrObjectID—The OneNote ID of the object you want to delete. The object can be a section group, section, or page.

  • dateExpectedLastModified—(Optional) The date and time that you think the object you want to delete was last modified. If you pass a non-zero value for this parameter, OneNote proceeds with the update only if the value you pass matches the actual date and time the object was last modified. Passing a value for this parameter helps prevent accidentally overwriting edits users made since the last time the object was modified.

  • deletePermanently—(Optional) true to permanently delete the content; false to move the content into the OneNote recycle bin for the corresponding Notebook (the default). If the Notebook is in OneNote 2007 format, no recycle bin exists, so the content is permanently deleted.

CreateNewPage Method

Description

Adds a new page to the section you specify. The new page is added as the last page of the section

Syntax

HRESULT CreateNewPage(
[in]BSTR bstrSectionID,
[out]BSTR * pbstrPageID);
[in,defaultvalue(npsDefault)]NewPageStyle npsNewPageStyle);

Parameters

  • bstrSectionID—A string that contains the OneNote ID of the section in which you want to create the new page.

  • pbstrPageID—(Output parameter) A pointer to the string into which the method writes the OneNote ID for the newly created page.

  • npsNewPageStyle—A value from the NewPageStyle enumeration that specifies the style of the page to be created.

The OneNote API includes the CreateNewPage method as a convenience. You can achieve the same result, with greater control over how the new page is positioned in the hierarchy, by calling the UpdateHierarchy method. The UpdateHierarchy method also lets you create subpages at the same time as you create a new page.

CloseNotebook Method

Description

Closes the specified notebook.

Syntax

HRESULT CloseNotebook(
[in]BSTR bstrNotebookID,
[in,defaultvalue(false)]VARIANT_BOOL force);

Parameters

  • bstrNotebookID—The OneNote ID of the notebook you want to close.

  • force—(Optional) true to close the notebook, even if there are changes in the notebook that OneNote cannot sync before closing; otherwise, false (the default).

You can use the CloseNotebook method to close the notebook you specify. When you call this method, OneNote synchronizes any offline files with current notebook content, if necessary, and then closes the specified notebook. After the method returns, the notebook no longer appears in the list of open notebooks in the OneNote user interface (UI).

GetHierarchyParent Method

Description

Gets the OneNote ID for the parent object of a OneNote object.

Syntax

HRESULT GetHierarchyParent (
[in]BSTR bstrObjectID,
[out]BSTR * pbstrParentID);

Parameters

  • bstrObjectID—A string that contains the OneNote ID of the object of which you want to find the parent object.

  • pbstrParentID—(Output parameter) A pointer to the string into which the method writes the OneNote ID of the parent object.

If the OneNote object has no parent object (for example, when a user wants to get the parent of a Notebook), an exception is thrown.

GetSpecialLocation Method

Description

Finds the path to the location where OneNote stores certain special items, such as backups, unfiled notes, and the default notebook.

Syntax

HRESULT GetSpecialLocation(
[in]SpecialLocation slToGet,
[out]BSTR * pbstrSpecialLocationPath);

Parameters

  • slToGet—One of the SpecialLocation enumeration values that specifies the special folder location to get.

  • pbstrSpecialLocationPath—(Output parameter) A pointer to the string into which you want OneNote to write the path of the special folder.

You can use this method to determine the location on disk of the Unfiled Notes folder. That is the folder in which OneNote stores notes that are created when you drag an item into OneNote, as well as notes that come directly from other applications (such as those that result when you click Send to OneNote in Microsoft Outlook or Microsoft Internet Explorer).

Page Content Methods

The methods described in this section enable you to discover, update, and delete the content on pages in OneNote notebooks, as well as to publish OneNote content.

GetPageContent Method

Description

Gets all of the content (in OneNote XML format) of the specified page.

Syntax

HRESULT GetPageContent(
[in]BSTR bstrPageID,
[out]BSTR * pbstrPageXmlOut,
[in,defaultvalue(piBasic)]PageInfo pageInfoToExport,
[in,defaultvalue(xsCurrent)]XMLSchema xsSchema);

Parameters

  • bstrPageId—The OneNote ID of the page whose content you want to get.

  • pbstrPageXmlOut—(Output parameter) A pointer to the string into which you want OneNote to write the XML output.

  • pageInfoToExport—(Optional) Specifies whether the GetPageContent method returns binary content, embedded in the XML code and base-64 encoded. Binary content can include, for example, images and ink data. The pageInfoToExport parameter also specifies whether to mark up the selection in the XML code that the GetPageContent method returns. It takes an enumerated value from the PageInfo enumeration.

  • xsSchema—(Optional) The version of the OneNote XML schema, of type XMLSchema, that you want to be output. You can specify whether you want XML Schema version 2013, 2010, 2007, or the current version.

    Note Note

    We recommend specifying a version of OneNote (such as xs2013) instead of using xsCurrent or leaving it blank, because this will allow your add-in to work with future versions of OneNote.

By default, to avoid excess length in the XML string it returns, OneNote does not embed binary content in the XML code. For the same reason, it does not mark up the current selection with selection attributes. Binary objects include a OneNote ID in their tags. To get a binary object, you call the GetBinaryPageContent method and pass it the OneNote ID you get from the GetPageContent method. You use the GetPageContent method when you do not need the binary data immediately.

UpdatePageContent Method

Description

Updates or modifies the content on the page.

Syntax

HRESULT UpdatePageContent(
[in]BSTR bstrPageChangesXmlIn,
[in,defaultvalue(0)]DATE dateExpectedLastModified,
[in,defaultvalue(xsCurrent)]XMLSchema xsSchema,
[in,defaultvalue(false)]VARIANT_BOOL force);

Parameters

  • bstrPageChangesXmlIn—A string that contains OneNote XML code that includes the changes you want to make to the page.

  • dateExpectedLastModified—(Optional) The date and time that you think the page you want to update was last modified. If you pass a non-zero value for this parameter, OneNote proceeds with the update only if the value you pass matches the actual date and time the page was last modified. Passing a value for this parameter helps prevent accidentally overwriting edits users made since the last time the page was modified.

  • xsSchema—(Optional) The version of the OneNote XML schema, of type XMLSchema, that you want to be output. You can specify whether you want XML schema version 2013, 2010, 2007, or the current version.

    Note Note

    We recommend specifying a version of OneNote (such as xs2013) instead of using xsCurrent or leaving it blank, because this will allow your add-in to work with future versions of OneNote.

  • force(Optional) true to update the page content, even if there is unknown data on the page from a future version of OneNote; otherwise, false (the default).

You can use this method to modify the page in various ways. For example, you can use the UpdatePageContent method to add an outline to a page, change the content of an outline, add images, add ink, move content, or modify text in outlines.

As a more specific example, you might use the GetPageContent method to export an existing page, make some changes to the XML code for the page, and then use the UpdatePageContent method to import the entire page again. Or, you might use this method to add new page objects, such as images, to the bottom of an existing page.

The only objects that you must include in the XML code that you pass to the UpdatePageContent method are page-level objects (such as outlines, images on the page, or ink on the page) that have changed. This method does not modify or remove page-level objects that you do not specify in the bstrPageChangesXmlIn parameter. The method entirely replaces page-level objects, such as outlines, whose IDs match those of the objects you pass. Consequently, you must fully specify all page-level objects in your code, including their existing content and changes you want to make to them.

For example, if your page contains an outline and a background page image, you can replace the outline and leave the image unchanged by completely specifying the outline in the XML code, using the ID of the existing outline, and not including the image in the code. Because the revised outline you include in the code completely replaces the existing outline, you must include the entire contents of the outline.

Also, the UpdatePageContent method modifies only element properties that you specify in the bstrPageChangesXmlIn parameter. For example, if you specify some, but not all, properties of the PageSettings element, the properties that you do not specify remain unchanged.

The following example shows how to use the UpdatePageContent method to change the title of a page and add some sample text to the page. Before running the code, substitute a valid page ID for the page ID shown in the code, so that the code works on your computer. You can get the page ID for a page by using the GetHierarchy method and examining the output.

C# Copy code Copy code
static void UpdatePageContent()
    {
        OneNote.Application onApplication = new OneNote.Application();
        String strImportXML;

        strImportXML = "<?xml version=\"1.0\"?>" +
            "<one:Page xmlns:one=\"http://schemas.microsoft.com/office/onenote/12/2004/onenote\"
            ID=\"{3428B7BB-EF39-4B9C-A167-3FAE20630C37}{1}{B0}\">" +
            "    <one:PageSettings RTL=\"false\" color=\"automatic\">" +
            "        <one:PageSize>" +
            "            <one:Automatic/>" +
            "        </one:PageSize>" +
            "        <one:RuleLines visible=\"false\"/>" +
            "    </one:PageSettings>" +
            "    <one:Title style=\"font-family:Calibri;
                 font-size:17.0pt\" lang=\"en-US\">" +
            "        <one:OE alignment=\"left\">" +
            "            <one:T>" +
            "                <![CDATA[My Sample Page]]>" +
            "            </one:T>" +
            "        </one:OE>" +
            "    </one:Title>" +
            "    <one:Outline >" +
            "        <one:Position x=\"120\" y=\"160\"/>" +
            "        <one:Size width=\"120\" height=\"15\"/>" +
            "        <one:OEChildren>" +
            "            <one:OE alignment=\"left\">" +
            "                <one:T>" +
            "                    <![CDATA[Sample Text]]>" +
            "                </one:T>" +
            "            </one:OE>" +
            "        </one:OEChildren>" +
            "    </one:Outline>" +
            "</one:Page>";

        // Update the page content.
        onApplication.UpdatePageContent(strImportXML, System.DateTime.MinValue);
    }

GetBinaryPageContent Method

Description

Returns a binary object, such as ink or images, on an OneNote page as a base-64-encoded string.

Syntax

HRESULT GetBinaryPageContent(
[in]BSTR bstrPageID,
[in]BSTR bstrCallbackID,
[out]BSTR * pbstrBinaryObjectB64Out);

Parameters

  • bstrPageID—The OneNote ID of the page that contains the binary object to get.

  • bstrCallBackID—The OneNote ID of the binary object you want to get. This ID, known as a callbackID, is in the OneNote XML code for a page returned by the GetPageContent method.

  • pbstrBinaryObectB64Out—(Output parameter) A pointer to a string into which OneNote writes the binary object as a base-64-encoded string.

DeletePageContent Method

Description

Deletes an object—such as an Outline, Ink, or Image object—from a page.

Syntax

HRESULT DeletePageContent(
[in]BSTR bstrPageID,
[in]BSTR bstrObjectID,
[in,defaultvalue(0)]DATE dateExpectedLastModified,
[in,defaultvalue(#)]VARIANT_BOOL force);

Parameters

  • bstrPageID—The OneNote ID of the page that contains the object to delete.

  • bstrObjectID—The OneNote ID of the object that you want to delete.

  • dateExpectedLastModified—(Optional) The date and time that you think the page that contains content you want to delete was last modified. If you pass a non-zero value for this parameter, OneNote proceeds with the deletion only if the value you pass matches the actual date and time the page was last modified. Passing a value for this parameter helps prevent accidentally overwriting edits made by users since the last time the page was modified.

  • force(Optional) true to update the page content, even if there is unknown data on the page from a future version of OneNote; otherwise, false (the default).

Publish Method

Description

Exports the page you specify to a file in any format that OneNote supports.

Syntax

HRESULT Publish(
[in]BSTR bstrHierarchyID,
[in]BSTR bstrTargetFilePath,
[in,defaultvalue(pfOneNote)]PublishFormat pfPublishFormat,
[in,defaultvalue(0)]BSTR bstrCLSIDofExporter);

Parameters

  • bstrHierarchyID—The OneNote ID of the hierarchy you want to export.

  • bstrTargetFilePath—The absolute path to the location where you want to save the resulting output file. The file you specify must be one that does not already exist at that location.

  • pfPublishFormat—One of the PublishFormat enumeration values that specifies the format in which you want the published page to be (for example, MTHML, PDF, and so on).

  • bstrCLSIDofExporter—The class ID (CLSID) of a registered COM application that can export Microsoft Windows enhanced metafiles (.emf). The COM application must implement the IMsoDocExporter interface. This parameter is included to permit third-party developers to write their own code to publish OneNote content in a custom format. For more information about the IMsoDocExporter interface, see Extending the Office 2007 Fixed-Format Export Feature.

Currently, OneNote supports the following file formats:

  • MHTML files (.mht)

  • Adobe Acrobat PDF files (.pdf)

  • XML Paper Specification (XPS) files (.xps)

  • OneNote 2013, 2010 or 2007 files (.one)

  • OneNote Package files (.onepkg)

  • Microsoft Word documents (.doc or .docx)

  • Microsoft Windows Enhanced Metafiles (.emf)

  • HTML files (.html)

This method produces exactly the same results you would get by clicking Publish in the UI and specifying the format.

Navigation Methods

The methods described in this section enable you to find, navigate to, and link to OneNote notebooks, section groups, sections, pages, and page objects.

NavigateTo Method

Description

Navigates to the specified object (for example, sections, pages, and Outline elements within pages).

Syntax

HRESULT NavigateTo(
[in]BSTR bstrHierarchyObjectID,
[in,defaultvalue(#)]BSTR bstrObjectID,
[in,defaultvalue(0)]VARIANT_BOOL fNewWindow);

Parameters

  • bstrHierarchyObjectID—The OneNote ID of the object you want to navigate to in the OneNote Hierarchy.

  • bstrObjectID—The OneNote ID of the object you want to navigate to on the OneNote page.

  • fNewWindow—(Optional) true to open specified object in a new OneNote window. false does not open a new OneNote window if one is open.

NavigateToUrl Method

Description

If passed a OneNote link (onenote://), opens the OneNote window to the corresponding location in OneNote. If the link is external to OneNote (such as http:// or file://), a security dialog box will appear. Upon dismissal, OneNote attempts to open the link and an HResult.hrObjectDoesNotExist error is returned.

Syntax

HRESULT NavigateTo(
[in]BSTR bstrUrl,
[in,defaultvalue(0)]VARIANT_BOOL fNewWindow);

Parameters

  • bstrUrl—A string that indicates where to navigate to. This could be a OneNote link, or any other URL, such as a web link or network location.

  • fNewWindow—(Optional) true to open the specified URL in a new OneNote window. false does not open a new OneNote window if one is open.

GetHyperLinkToObject Method

Description

Gets a OneNote hyperlink to the specified notebook, section group, section, page, or page object.

Syntax

HRESULT GetHyperlinkToObject(
[in] BSTR bstrHierarchyID,
[in] BSTR bstrPageContentObjectID,
[out] BSTR * pbstrHyperlinkOut);

Parameters

  • bstrHierarchyID—The OneNote ID for the notebook, section group, section, or page for which you want a hyperlink.

  • bstrPageContentObjectID—(Optional) The OneNote ID for the object within the page for which you want a hyperlink. For example, the object can be an outline or Outline element. If you pass an empty string (""), the returned link points to the notebook, section group, section, or page that you specified in the bstrHierarchyID parameter. If you pass a non-empty string for the bstrPageContentObjectID parameter, the bstrHierarchyID parameter must be a reference to the page that contains the specified object.

  • pbstrHyperlinkOut—(Output parameter) A pointer to a string into which the GetHyperlinkToObject method writes the output hyperlink text.

When you attempt to navigate to the resulting link, OneNote opens and displays the specified object in the browser.

GetWebHyperlinktoObject

Description

Returns a hyperlink to an object that opens in the OneNote Web Client.

Syntax

HRESULT GetWebHyperlinkToObject (
[in] BSTR bstrHierarchyID,
[in] BSTR bstrPageContentObjectID,
[out] BSTR * pbstrHyperlinkOut);

Parameters

  • bstrHierarchyID - The OneNote ID for the notebook, section group, section or page for which you want a web hyperlink.

  • bstrPageContentObjectID - (Optional) The OneNote ID for the object within the page for which you want a hyperlink. For example, the object can be an outline or Outline element. If you pass an empty string (""), the returned link points to the notebook, section group, section, or page that you specified in the bstrHierarchyID parameter. If you pass a non-empty string for the bstrPageContentObjectID parameter, the bstrHierarchyID parameter must be a reference to the page that contains the specified object.

  • pbstrHyperlinkOut - (Output parameter) A pointer to a string into which the GetWebHyperlinkToObject method writes the output hyperlink text. If a web hyperlink cannot be created for the notebook, a null value is returned.

FindPages Method

Description

Returns a list of pages that match the specified query term.

Syntax

HRESULT FindPages(
[in]BSTR bstrStartNodeID,
[in]BSTR bstrSearchBSTR,
[out]BSTR * pbstrHierarchyXmlOut,
[in,defaultvalue(#)]VARIANT_BOOL fIncludeUnindexedPages,
[in,defaultvalue(0)]VARIANT_BOOL fDisplay,
[in,defaultvalue(#)]XMLSchema xsSchema);

Parameters

  • bstrStartNodeID—The node (root, notebook, section group, or section) below which to search for content. This parameter sets the scope for the search.

  • bstrSearchString—The search string. Pass exactly the same string that you would type into the search box in the OneNote UI. You can use bitwise operators, such as AND and OR, which must be all uppercase.

  • pbstrHierarchyXmlOut—(Output parameter) A pointer to a string into which you want OneNote to write the output XML string. The resulting XML string contains the notebook hierarchy from the root downward to, and including, any pages that match the search string. For example, the FindPages method does not list sections that have no page matches in the hierarchy. Also, if only one page in a single section matches the string, the returned hierarchy includes the path to that section and page, but to no other parts of the notebook hierarchy.

  • fIncludeUnindexedPages—(Optional) true to search pages that have not been indexed by Windows Search; otherwise, false.

  • fDisplay—(Optional) true to also run the search in the UI for the user, just as if the user had typed it themselves. false to perform the query with no change to the UI (the default).

  • xsSchema—(Optional) The OneNote schema version of the string pbstrHierarchyXmlOut. This optional value is used to specify the version of the OneNote XML schema that contains the pbstrHierarchyXmlOut string. If this value is not specified, OneNote will assume that the XML is in schema version xsCurrent.

    Note Note

    We recommend specifying a version of OneNote (such as xs2013) instead of using xsCurrent or leaving it blank, because this will allow your add-in to work with future versions of OneNote.

FindPages works only if you have Microsoft Search 3.0 or 4.0 installed on your computer. Windows Vista and Windows 7 include this component. However, if you are running an earlier version of Windows, you must install Windows Search for FindPages to work.

FindMeta Method

Description

Returns a list of OneNote objects that contain metadata that matches the specified query term.

Syntax

HRESULT FindMeta (
[in]BSTR bstrStartNodeID,
[in]BSTR bstrSearchBSTRName,
[out]BSTR * pbstrHierarchyXmlOut,
[in,defaultvalue(#)]VARIANT_BOOL fIncludeUnindexedPages,
[in,defaultvalue(#)]XMLSchema xsSchema);

Parameters

  • bstrStartNodeID—The node (root, notebook, section group, or section) below which to search for content. This parameter sets the scope for the search.

  • bstrSearchStringName—The search string. Pass in any part of the metadata name. If you pass in an empty string or a null value, all objects that have metadata will match the query.

  • pbstrHierarchyXmlOut—(Output parameter) A pointer to a string into which you want OneNote to write the output XML string. The resulting XML string contains the notebook hierarchy from the root downward to, and including, any pages that match the search string. For example, the FindPages method does not list sections that have no page matches in the hierarchy. Also, if only one page in a single section matches the string, the returned hierarchy includes the path to that section and page, but to no other parts of the notebook hierarchy.

  • fIncludeUnindexedPages—(Optional) true to search pages that have not been indexed by Windows Search; otherwise, false.

  • xsSchema—(Optional) The OneNote schema version of the string pbstrHierarchyXmlOut. This optional value is used to specify the version of the OneNote XML schema that contains the pbstrHierarchyXmlOut string. If this value is not specified, OneNote will assume that the XML is in schema version xsCurrent.

    Note Note

    We recommend specifying a version of OneNote (such as xs2013) instead of using xsCurrent or leaving it blank, because this will allow your add-in to work with future versions of OneNote.

FindMeta works only if you have Microsoft Windows Search 3.0 or 4.0 installed on your computer. Windows Vista and Windows 7 include this component. However, if you are running an earlier version of Windows, you must install Windows Search for FindMeta to work.

Functional Methods

The methods described in this section enable you to perform certain actions or set parameters within the OneNote application.

MergeFiles Method

Description

Allows users to merge changes for the same file into one. For the files to be considered the same, they must have the same OneNote ID.

Syntax

HRESULT MergeFiles (
[in]BSTR bstrBaseFile,
[in]BSTR bstrClientFile,
[in]BSTR bstrServerFile,
[in]BSTR bstrTargetFile);

Parameters

  • bstrBaseFile—The path string to the .one file location of the initial state of the file.

  • bstrClientFile—The path string to the .one file location of the second set of changes to be merged with the base file after the server file changes are merged with the base.

  • bstrServerFile—The path string to the .one file location of the first set of changes to be merged with the base file.

  • bstrTargetFile—The path string to the .one file location of the file with the merged changes.

The MergeFiles method was intended for mobile scenarios in which multiple versions of an OneNote file may exist.

MergeSections Method

Description

Merges the content of one section into another in OneNote.

Syntax

HRESULT MergeSections (
[in]BSTR bstrSectionSourceId,
[in]BSTR bstrSectionDestinationId);

Parameters

  • bstrSectionSourceId—The OneNote ID of the section to be merged.

  • bstrSectionDestinationId—The OneNote ID of the section to be merged into. The source section will be merged into this destination section.

This method performs the same operation as the Merge into Another Section feature that is visible when you right-click a section.

QuickFiling Method

Description | Returns an instance of the IQuickFilingDialog dialog box, which can be used to select a location within the OneNote hierarchy tree.
Syntax | HRESULT QuickFiling ( );

SyncHierarchy Method

Description | Forces OneNote to sync the specified object with the source file on disk.
Syntax | HRESULT SyncHierarchy ( [in]BSTR bstrHierarchyID);
Parameters | bstrHierarchyID—The OneNote ID of the object to be synced.

SetFilingLocation Method

Description

Allows users to specify where and how certain types of content should be filed in OneNote.

Syntax

HRESULT SetFilingLocation (
[in]FilingLocation flToSet,
[in]FilingLocationType fltToSet,
[in]BSTR bstrFilingSectionID);

Parameters

  • flToSet—The object type of the filing location to set.

  • fltToSet—The location in which to file the type.

  • bstrFilingSectionID—The OneNote ID of the section or page at which location you want to set. If not applicable, the user can pass in null or an empty string.

The types of content that can be filed include Outlook items and Web Notes from Internet Explorer that are imported to OneNote through the Send to OneNote command in each application. The filing location of items that are printed into OneNote can also be set with this method.

Properties

This section describes the properties of the Application interface.

Property | Description
Windows | Gives users access to opened OneNote windows. This property allows users to enumerate through the set of OneNote windows and modify certain window properties. For more information, see Windows Interfaces.
COMAddIns | Returns the COMAddIns collection for OneNote. This collection contains all of the COM add-ins that are available to OneNote. The Count property of the COMAddins collection returns the number of available COM add-ins. For more information, see the COMAddIns object.
LanguageSettings | Enables you to access some APIs to change the common language settings of OneNote.

Events

This section describes the events of the Application interface.

Caution note Caution

Events cannot currently be added in managed code.

OnNavigate Event

Description | Allows a user to assign a function to be called when the OneNote UI is navigated away from the current OneNote location.
Syntax | Event OnNavigate ( );

OnHierarchyChange Method

Description | Allows a user to assign a function to be called any time the OneNote hierarchy changes (for example, adding or deleting pages, or moving sections). Hierarchy changes are batched, so if multiple changes occur at or near the same time, OneNote raises the event once.
Syntax | Event OnHierarchyChange ( BSTR bstrActivePageID);
Parameters | bstrActivePageID—Passes the OneNote ID of the active page.

See also

Concepts

OneNote 2013 Developer Reference

© 2013 Microsoft Corporation. All rights reserved.


Enumerations (OneNote 2013 Developer Reference)

 Copy code hover
[image]

Enumerations (OneNote 2013 Developer Reference)
See also Send feedback

This topic describes the enumerations in the OneNote 2013 object model.

CreateFileType

When passed to the OpenHierarchy method, specifies the type of object to create, if any, if the path passed to the method does not yet exist.

Member | Value | Description
cftNone | 0 | Creates no new object.
cftNotebook | 1 | Creates a notebook by using the specified name and location.
cftFolder | 2 | Creates a section group by using the specified name and location.
cftSection | 3 | Creates a section by using the specified name and location.

DockLocation

Indicates the docked location of a OneNote 2013 window by using the Window interface. When set to the DockedLocation property, specifies the location at which to dock a OneNote window. This enumeration is new in OneNote 2013.

Member | Value | Description
dlDefault | -1 | The OneNote window is docked at the default location on the desktop.
dlLeft | 1 | The OneNote window is docked on the left side of the desktop.
dlRight | 2 | The OneNote window is docked on the right side of the desktop.
dlTop | 3 | The OneNote window is docked at the top of the desktop.
dlBottom | 4 | The OneNote window is docked at the bottom of the desktop.

FilingLocation

When passed to the SetFilingLocation method, specifies what type of content the filing location is set for when the content type is sent to OneNote. This enumeration is new in OneNote 2013.

Member | Value | Description
flEMail | 0 | Sets where Outlook email messages will be filed.
flContacts | 1 | Sets where Outlook contacts will be filed.
flTasks | 2 | Sets where Outlook tasks will be filed.
flMeetings | 3 | Sets where Outlook meetings will be filed.
flWebContent | 4 | Sets where Internet Explorer contents will be filed.
flPrintOuts | 5 | Sets where printouts from the OneNote printer will be filed.

FilingLocationType

When passed to the SetFilingLocation method, specifies where content that is sent to OneNote is filed. This enumeration is new in OneNote 2013.

Member | Value | Description
fltNamedSectionNewPage | 0 | Sets content to be filed on a new page in a specified section.
fltCurrentSectionNewPage | 1 | Sets content to be filed on a new page in the current section.
fltCurrentPage | 2 | Sets content to be filed on the current page.
fltNamedPage | 4 | Sets content to be filed on a specified page.

HierarchyElement

When assigned to the TreeDepth property of the IQuickFilingDialog interface, specifies the depth of the OneNote tree to display when the quick filing dialog is rendered. When passed to the AddButton method of the IQuickFilingDialog object, references certain elements in the OneNote hierarchy. This enumeration is new in OneNote 2013.

Member | Value | Description
heNone | 0 | Refers to no element.
heNotebooks | 1 | Refers to the Notebook elements.
heSectionGroups | 2 | Refers to the Section Group elements.
heSections | 4 | Refers to the Section elements.
hePages | 8 | Refers to the Page elements.

HierarchyScope

When passed to the GetHierarchy method, specifies the lowest level to get in the notebook node hierarchy.

Member | Value | Description
hsSelf | 0 | Gets just the start node specified and no descendants.
hsChildren | 1 | Gets the immediate child nodes of the start node, and no descendants in higher or lower subsection groups.
hsNotebooks | 2 | Gets all notebooks below the start node, or root.
hsSections | 3 | Gets all sections below the start node, including sections in section groups and subsection groups.
hsPages | 4 | Gets all pages below the start node, including all pages in section groups and subsection groups.

NewPageStyle

When passed to the CreateNewPage method, specifies the style of the new page.

Member | Value | Description
npsDefault | 0 | Creates a page that has the default page style.
npsBlankPageWithTitle | 1 | Creates a blank page that has a title.
npsBlankPageNoTitle | 2 | Creates a blank page that has no title.

NotebookFilterOutType

When passed to the NotebookFilterOut method of the QFD object, specifies what notebooks to display when the QFD box is rendered.

Member | Value | Description
nfoLocal | 1 | Allow only Local Notebooks.
nfoNetwork | 2 | Allows UNC or SharePoint Notebooks.
nfoWeb | 4 | Allows SkyDrive notebooks.
nfoNoWacUrl | 8 | Any notebooks in locations that do not have a web client.

PageInfo (Updated for OneNote 2013)

When passed to the GetPageContent method, specifies the type of information to return with the page content.

Member | Value | Description
piBasic | 0 | Returns only basic page content, without selection markup, file types for binary data objects and binary data objects. This is the standard value to pass.
piBinaryData | 1 | Returns page content with no selection markup, but with all binary data.
piSelection | 2 | Returns page content with selection markup, but no binary data.
piBinaryDataSelection | 3 | Returns page content with selection markup and all binary data.
piFileType | 4 | Returns page content with file type info for binary data objects.
piBinaryDataFileType | 5 | Returns page content with file type info for binary data objects and binary data objects
piSelectionFileType | 6 | Returns page content with selection markup and file type info for binary data.
piAll | 7 | Returns all page content.

PublishFormat

When passed to the Publish method, specifies the format in which the published page will appear.

Member | Value | Description
pfOneNote | 0 | Published page is in the .one format.
pfOneNotePackage | 1 | Published page is in the .onepkg format.
pfMHTML | 2 | Published page is in the .mht format.
pfPDF | 3 | Published page is in the .pdf format.
pfXPS | 4 | Published page is in the .xps format.
pfWord | 5 | Published page is in the .doc or .docx format.
pfEMF | 6 | Published page is in the enhanced metafile (.emf) format.
pfHTML | 7 | Published page is in the .html format. This member is new in OneNote 2013.
pfOneNote2007 | 8 | Published page is in the 2007 .one format. This member is new in OneNote 2013.

RecentResultType

When passed to the SetRecentResults method of the IQuickFilingDialog object, specifies what recent result list to display when the Quick Filing dialog box is rendered. Recent result lists are used to track the set of OneNote locations that the user selects in the Quick Filing dialog box. There are three recent-result lists in OneNote 2013 that track filing, search, and linking actions. This enumeration is new in OneNote 2013.

Member | Value | Description
rrtNone | 0 | Sets no recent-result list to be rendered.
rrtFiling | 1 | Sets the "Filing" recent-result list to be rendered.
rrtSearch | 2 | Sets the "Search" recent-result list to be rendered.
rrtLinks | 3 | Sets the "Links" recent-result list to be rendered.

SpecialLocation

When passed to the GetSpecialLocation method, specifies the special location path to get.

Member | Value | Description
slBackupFolder | 0 | Gets the path to the Backup Folders folder location.
slUnfiledNotesSection | 1 | Gets the path to the Unfiled Notes folder location.
slDefaultNotebookFolder | 2 | Gets the path to the Default Notebook folder location.

TreeCollapsedStateType

When passed to the TreeCollapsedState method of the QFD object, specifies whether the hierarchy tree should be expanded or collapsed.

Member | Value | Description
tcsExpanded | 0 | Sets the hierarchy tree to expanded.
tcsCollapsed | 1 | Sets the hierarchy tree to collapsed.

XMLSchema (Updated for OneNote 2013)

When passed to one of the following methods, specifies the version of the OneNote XML schema to use:

  • OneNote15.Application.GetPageContent

  • OneNote15.Application.FindMeta

  • OneNote15.Application.FindPages

  • OneNote15.Application.GetHierarchy

  • OneNote15.Application.GetPageContent

  • OneNote15.Application.UpdateHierarchy

  • OneNote15.Application.UpdatePageContent

Member

Value

Description

xs2007

0

References the OneNote 2007 schema.

xs2010

1

References the OneNote 2010 schema.

xs2013

2

References the OneNote 2013 schema.

xsCurrent

2

References the schema of the current OneNote version.

Note Note

We do not recommend using xsCurrent in most cases, as it can cause compatibility issues with future versions of OneNote. Instead specify the version of the schema that your app was built to handle, like xs2013.

See also

Welcome to the OneNote 2013 developer reference


Error codes (OneNote 2013)

 Copy code hover
[image]

Error codes (OneNote 2013)
See also Send feedback

This topic lists the error codes in the OneNote 2013 object model.

HResult | Value | Description
hrMalformedXML | 0x80042000 | The XML is not well-formed.
hrInvalidXML | 0x80042001 | The XML is invalid.
hrCreatingSection | 0x80042002 | The section could not be created.
hrOpeningSection | 0x80042003 | The section could not be opened.
hrSectionDoesNotExist | 0x80042004 | The section does not exist.
hrPageDoesNotExist | 0x80042005 | The page does not exist.
hrFileDoesNotExist | 0x80042006 | The file does not exist.
hrInsertingImage | 0x80042007 | The image could not be inserted.
hrInsertingInk | 0x80042008 | The ink could not be inserted.
hrInsertingHtml | 0x80042009 | The HTML could not be inserted.
hrNavigatingToPage | 0x8004200a | The page could not be opened.
hrSectionReadOnly | 0x8004200b | The section is read-only.
hrPageReadOnly | 0x8004200c | The page is read-only.
hrInsertingOutlineText | 0x8004200d | The outline text could not be inserted.
hrPageObjectDoesNotExist | 0x8004200e | The page object does not exist.
hrBinaryObjectDoesNotExist | 0x8004200f | The binary object does not exist.
hrLastModifiedDateDidNotMatch | 0x80042010 | The last modified date does not match.
hrGroupDoesNotExist | 0x80042011 | The section group does not exist.
hrPageDoesNotExistInGroup | 0x80042012 | The page does not exist in the section group.
hrNoActiveSelection | 0x80042013 | There is no active selection.
hrObjectDoesNotExist | 0x80042014 | The object does not exist.
hrNotebookDoesNotExist | 0x80042015 | The notebook does not exist.
hrInsertingFile | 0x80042016 | The file could not be inserted.
hrInvalidName | 0x80042017 | The name is invalid.
hrFolderDoesNotExist | 0x80042018 | The folder (section group) does not exist.
hrInvalidQuery | 0x80042019 | The query is invalid.
hrFileAlreadyExists | 0x8004201a | The file already exists.
hrSectionEncryptedAndLocked | 0x8004201b | The section is encrypted and locked.
hrDisabledByPolicy | 0x8004201c | The action is disabled by a policy.
hrNotYetSynchronized | 0x8004201d | OneNote has not yet synchronized content.
hrLegacySection | 0x8004201E | The section is from OneNote 2007 or earlier.
hrMergeFailed | 0x8004201F | The merge operation failed.
hrInvalidXMLSchema | 0x80042020 | The XML Schema is invalid.
hrFutureContentLoss | 0x80042022 | Content loss has occurred (from future versions of OneNote).
hrTimeOut | 0x80042023 | The action timed out.
hrRecordingInProgress | 0x80042024 | Audio recording is in progress.
hrUnknownLinkedNoteState | 0x80042025 | The linked-note state is unknown.
hrNoShortNameForLinkedNote | 0x80042026 | No short name exists for the linked note.
hrNoFriendlyNameForLinkedNote | 0x80042027 | No friendly name exists for the linked note.
hrInvalidLinkedNoteUri | 0x80042028 | The linked note URI is invalid.
hrInvalidLinkedNoteThumbnail | 0x80042029 | The linked note thumbnail is invalid.
hrImportLNTThumbnailFailed | 0x8004202A | The importation of linked note thumbnail failed.
hrUnreadDisabledForNotebook | 0x8004202B | Unread highlighting is disabled for the notebook.
hrInvalidSelection | 0x8004202C | The selection is invalid.
hrConvertFailed | 0x8004202D | The conversion failed.
hrRecycleBinEditFailed | 0x8004202E | Edit failed in the Recycle Bin.

The following lists the new error codes for OneNote 2013.

HResult | Value | Description
hrIMConversationTypeInvalid | 0x8004202F | Returned by UpdatePageContent if IMConversationType page node property was to a value other than 0,1,2 or 3
hrAppInModalUI | 0x80042030 | A modal dialog is blocking the app.

See also

Welcome to the OneNote 2013 developer reference


OneNote 2013 Developer Reference Copyright Information

 Copy code hover
[image]

OneNote 2013 Developer Reference Copyright Information
Send feedback

This document is provided "as-is". Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2012 Microsoft Corporation. All rights reserved.

Microsoft, Access, ActiveX, ClearType, Excel, FrontPage, InfoPath, IntelliSense, JScript, MSDN, MS-DOS, MSN, OneNote, Outlook, PowerPoint, SharePoint, Silverlight, SmartArt, SQL Server, Visio, Visual Basic, Visual C#, Visual C++, Visual Studio, Win32, Windows, Windows PowerShell, Windows Server, and Windows Vista are trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.


Office 2013 documentation copyright notice

 Copy code hover
[image]

Office 2013 documentation copyright notice
Send feedback

Published: July 16, 2012

This document is provided "as-is". Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2013 Microsoft Corporation. All rights reserved.

Microsoft, Access, ActiveX, ClearType, Excel, FrontPage, InfoPath, IntelliSense, JScript, MSDN, MS-DOS, MSN, OneNote, Outlook, PowerPoint, SharePoint, Silverlight, SmartArt, SQL Server, Visio, Visual Basic, Visual C#, Visual C++, Visual Studio, Win32, Windows, Windows PowerShell, Windows Server, and Windows Vista are trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.